home *** CD-ROM | disk | FTP | other *** search
/ AGA Toolkit '97 / The AGA Toolkit '97.iso / miscellaneous / help / dos / dosman / man / execute < prev    next >
Encoding:
Text File  |  1996-09-07  |  8.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4.              Execute(V1.3, 2.x, and 3.x in C:)
  5.  
  6.  
  7.  
  8.      NAME
  9.             Execute - Cause the shell to execute commands from a 
  10.         file.
  11.  
  12.      SYNOPSIS
  13.             Execute [Filename] [ARGS...]
  14.  
  15.      DESCRIPTION
  16.             Execute causes the shell or CLI to read the commands 
  17.         from the filename specified as Execute's input argument.  
  18.         When the end of the file is reached, control returns to 
  19.         the keyboard.  You can force the Shell to abort any 
  20.         script file processing by typing a C-d (Control D) 
  21.         sequence while the script is being executed.
  22.  
  23.             You can even include nest an Execute inside your 
  24.         script to cause one script to call another one during its 
  25.         execution.
  26.  
  27.             In AmigaDOS 1.3 and above, you can execute a script 
  28.         without typing EXECUTE and just typing name of the script 
  29.         if the 'S' bit is set.
  30.  
  31.          
  32.      KEYWORDS
  33.           FILENAME
  34.             The name of the script to execute.
  35.  
  36.           ARGS
  37.             Any arguments to be passed to the file. These may be 
  38.         any valid AmigaDOS string (including filenames and all 
  39.         sorts of devices.    
  40.  
  41.      DIRECTIVES
  42.             Execute recognizes several special commands known as 
  43.         Directives.  Each of these Directives begins with a DOT 
  44.         '.', but this character can be redefined if needed.  
  45.         Execute is reasonably flexible in allowing you to 
  46.         redefine its special characters, which is quite 
  47.         fortunate, as you will soon see.
  48.  
  49.             In order for Execute to recognize these directives, 
  50.         the DOT character must be placed at the beginning of the 
  51.         line, and the directive name must follow immediately, 
  52.         with no intervening whitespace.  You can also use the DOT 
  53.         (again, at the beginning of a line only) to introduce a 
  54.         comment. This usage is ".<whitespace>Anything" where 
  55.         whitespace is any of space, tab or newline.
  56.  
  57.             Many of these directives deal with passing arguments 
  58.         to scripts and establishing defaults for arguments.  
  59.         These are described below:
  60.  
  61.      .KEY and PARAMETERS
  62.             The .KEY directive (which may be abbreviated as .K) 
  63.         is used to declare the names of parameters which will be 
  64.         used in the course of the script file. Note that these 
  65.         are not environment variables.  If you intend to pass 
  66.         arguments to a script file, it is wise to use this 
  67.         directive as the first line of a file. If the first 
  68.         non-empty line (i.e., a line which contains anything 
  69.         other than a newline) does not contain a dot command 
  70.         (directive), then the arguments will not be processed.
  71.  
  72.             The .KEY directive accepts any legal template.  These 
  73.         are the same kinds of templates you see all the time in 
  74.         the AmigaDOS commands. Note that currently, there is no 
  75.         support for multiargs (the /... template type) in 
  76.         scripts, and so you should not use this in your 
  77.         templates.  All the usual processing associated with 
  78.         templates is active in scripts, including the '?' display 
  79.         of the template, and position independent arguments.
  80.  
  81.             When you use the .KEY directive, Execute matches up 
  82.         the users arguments with your template keywords, and if 
  83.         no error occurred, scans the file for any items 
  84.         surrounded with the BRA KET characters.  These are 
  85.         initially '<' and '>', which is quite unfortunate, since 
  86.         these tend to conflict with the IO redirection operators.  
  87.         It is wise to change these to another character using the 
  88.         .BRA and .KET operators (see below).
  89.  
  90.             When a BRAKET sequence is encountered, Execute 
  91.         replaces the keyword inside the BRAKET with the users 
  92.         argument.  If the user did not enter an argument for that 
  93.         keyword, and there is no default setting for this 
  94.         keyword, then Execute removes the argument all together, 
  95.         resulting in a NULL string.  Arguments that do not take 
  96.         an argument, for example, switches (template type /S), 
  97.         are handled somewhat differently.  If the user supplied 
  98.         the switch on the command line, then the braket sequence 
  99.         is replaced by the actual name of the switch, otherwise, 
  100.         it is null.
  101.  
  102.      DEFAULT VALUES FOR PARAMETERS
  103.             This assigns the value string to all occurrences of 
  104.         the substitution argument described below.
  105.  
  106.             You can set default values for your variables in two 
  107.         ways.  The first way is to use the .DEFAULT directive.  
  108.         .DEFAULT (which may be abbreviated as .DEF) takes a 
  109.         template keyword and a default value.  If that keyword 
  110.         does not have a value at the time the .DEFAULT statement 
  111.         is scanned, then Execute binds the value to that keyword.  
  112.         Here is an example of its use:
  113.  
  114.             .DEFAULT Foobar "Testing123"
  115.  
  116.  
  117.             Another way to set default values is by using the 
  118.         DOLLAR (initially each time the parameter is used, it 
  119.         does not set it permanently:
  120.  
  121.             Echo "<Foobar$Testing123>"
  122.  
  123.             Note that a .DEFAULT statement will override all 
  124.         following DOLLAR defaults. The decision as to which to 
  125.         use is usually based on how many times you use that 
  126.         parameter.  If you only use it once, then either will do. 
  127.         If you use it many times, then .DEFAULT is probably the 
  128.         simplest.  Also note that there is not a conflict between 
  129.         this use of the DOLLAR and the use of the dollar during 
  130.         Shell environment expansion: The DOLLAR is special to 
  131.         Execute only inside of BRAKETS, and the shell expands the 
  132.         environment variables only after Execute has parsed the 
  133.         file.  Unless you use environment variables inside of 
  134.         BRAKETs, there should be no need to change your .DOLLAR 
  135.         character.
  136.  
  137.             You can also use a double DOLLAR inside of brackets. 
  138.         This will be replaced by the current CLI number.
  139.  
  140.      CHANGING THE META CHARACTERS
  141.             The following directives are used to change the 
  142.         default meta characters used by Execute.  Each take a 
  143.         single character as their argument.
  144.  
  145.           .BRA and .KET
  146.             These change the bracket characters (initially '<' 
  147.         and '>', respectively) to something else.  It is highly 
  148.         recommended you make a habit of doing this, whether you 
  149.         think you need to or not.  Good characters to use instead 
  150.         are the curly braces ('{' '}') since these are not needed 
  151.         for anything else, currently.
  152.  
  153.           .DOT 
  154.             This changes the DOT character (initially '.').
  155.  
  156.           .DOL or .DOLLAR
  157.             This changes the DOLLAR character (initially '$').
  158.  
  159.      MISCELLANEOUS
  160.             Execute may be nested, i.e., you may include Execute 
  161.         commands in scripts, which can also contain Execute 
  162.         commands.
  163.  
  164.             Execute will sometimes need to write a temporary 
  165.         file.  If you have assigned a directory or device to T:, 
  166.         then this location will be used.  If not, and there is a 
  167.         :T directory for the current directory, then Execute will 
  168.         create the assignment, and use this directory.  
  169.         Otherwise, it will attempt to create both the directory 
  170.         and the assignment in the current directory. EXECUTE uses 
  171.         <$$> with the task number of the CLI from which it is run 
  172.         to create this.
  173.  
  174.      EXAMPLES
  175.  
  176.             1. To execute a script named RunThis located on Df0:
  177.  
  178.             EXECUTE df0:RunThis
  179.  
  180.             2. Here is an example of a KEY directive which 
  181.         contains a switch.  This illustrates a good way to handle 
  182.         and use /s style arguments in script files.
  183.  
  184.              .KEY MySwitch/s
  185.  
  186.              IF "<MySwitch>" EQ "MySwitch"
  187.                 Echo "The switch is on!"
  188.              ELSE
  189.                 Echo "The switch is off!"
  190.              ENDIF
  191.  
  192.           If the user doesn't supply MySwitch as an argument on the
  193.           command line, then the comparison will fail (the first
  194.           argument will be ""), otherwise, the comparison will succeed
  195.           (the switch is "on").
  196.  
  197.      SEE ALSO
  198.           If Skip Failat Lab Echo Quit
  199.